/**
 * Copyright 2008 Adam Ruggles.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package kiff.service;

import java.util.List;

import kiff.entity.User;
import kiff.exception.ServiceLayerException;


/**
 * Service Interface all Services must implement this interface.
 * @author Adam
 * @version $Id: CoreService.java 73 2008-12-02 06:28:25Z a.ruggles $
 * @param <T> The Type for the implementation of the Service bean. 
 */
public interface CoreService<T> {
    /**
     * Returns a entity of type T by it's id or null if it could not be found.
     * @param id The id of the entity to return.
     * @return An entity of type T or null.
     * @throws ServiceLayerException If an exception occurs in the service layer.
     */
    T find(Object id) throws ServiceLayerException;
    /**
     * Returns all objects of type T.
     * @return A java.util.List of all objects of type T.
     * @throws ServiceLayerException If an exception occurs in the service layer.
     */
    List<T> findAll() throws ServiceLayerException;
    /**
     * Inserts an object of type T.
     * @param entity The entity object to save.
     * @param user The user requesting the insert.
     * @throws ServiceLayerException If an exception occurs in the service layer.
     */
    void insert(T entity, User user) throws ServiceLayerException;
    /**
     * Refreshes the state of the entity from the database, overwriting changes made to the entity, if any.
     * @param entity The entity to refresh.
     * @throws ServiceLayerException If an exception occurs in the service layer.
     */
    void refresh(T entity) throws ServiceLayerException;
    /**
     * Removes the object of type T.
     * @param entity The entity to remove.
     * @param user The user requesting the removal.
     * @throws ServiceLayerException If an exception occurs in the service layer.
     */
    void remove(T entity, User user) throws ServiceLayerException;
    /**
     * Updates an object of type T.
     * @param entity The entity object to save.
     * @param user The user requesting the update.
     * @return The persisted instance of the entity object.
     * @throws ServiceLayerException If an exception occurs in the service layer.
     */
    T update(T entity, User user) throws ServiceLayerException;
}
